---
title: "Codemod Registry"
sidebarTitle: 'Registry'
---

The **Codemod Registry** is a centralized repository for discovering, consuming, and distributing [Codemod packages](/cli/packages/quickstart). It enables the community to share reusable code transformation tools and allows organizations to maintain private codemods for their internal use. It provides:

- **Package discovery** – Search and browse codemods by language, framework, category, and keywords
- **Version management** – Semantic versioning with support for version pinning
- **Scoped packages** – Organize packages by organization or user scope (e.g., `@nodejs/create-require-from-path`)
- **Access control** – Configure codemod access types: `public` or `private`
- **Direct execution** – Run packages directly from the registry using `npx codemod <package-name>`

## Package Access Types

Codemod packages can have different access levels that control who can discover and run them:

### Public Access

Packages with `public` access are discoverable and runnable by anyone. They appear in public search results and can be used by the entire community.

**Use cases:**
- Community-shared codemods for open-source projects
- Framework migration tools for public use
- Educational or example codemods

**Features:**
- Free to use and publish
- Discoverable by everyone
- Browse at [codemod.com/registry](https://codemod.com/registry)

### Private Access

Packages with `private` access are only accessible to the owner or organization members. Available for Pro and Enterprise plan customers.

**Use cases:**
- Maintain proprietary codemods for company-specific patterns
- Share internal codemods across teams
- Keep sensitive transformations private
- Enforce organization standards

**Access:**
- Requires organization membership (for organization-scoped packages)
- Packages can be scoped to your organization (e.g., `@your-org/internal-codemod`)
- Configured through organization settings in the [Codemod app](https://app.codemod.com)

<Info>
To use a scoped package name, first reserve the scope by installing the [Codemod GitHub App](https://github.com/apps/codemod) on a repository in your GitHub organization. Only organization admins can publish codemods under that scope.
</Info>

## Discovering Packages

**Browse the Registry:**

Visit the [Codemod Registry](https://go.codemod.com/registry) web interface to browse packages.

**Search from CLI:**

Use the `codemod search` command to find packages:

```bash
# Search for packages
npx codemod search [query]
```

Learn more about search options in the [CLI Reference](/cli/cli-reference#codemod-search).

## Running Packages from the Registry

Run packages directly from the registry without downloading them first:

```bash
# Run a package (scoped or unscoped)
npx codemod @nodejs/create-require-from-path
```

<Info>
  When you run a package from the registry, Codemod CLI automatically downloads and caches it locally. Subsequent runs use the cached version for faster execution.
</Info>

**Version Pinning:**

For reproducible runs in production, always specify an exact version:

```bash
# Pin to specific version
npx codemod @nodejs/create-require-from-path@1.1.0

# Uses latest version (may change)
npx codemod @nodejs/create-require-from-path
```

Version pinning ensures your codemods behave consistently across different environments and over time.

## Publishing Packages

### Prerequisites

Before publishing, you need to:

1. **Create a Codemod package** – Use `npx codemod init` to scaffold a new package. Learn more about [building Codemod packages](/cli/packages/building-workflows).
2. **Authenticate** – Login to the registry using `npx codemod login`. Learn more about [authentication](/cli/cli-reference#codemod-login).

### Publishing Your First Package

```bash
# 1. Navigate to your codemod directory
cd my-codemod

# 2. Publish (first publish must be interactive)
npx codemod publish
```

During the first publish, you'll be prompted to:
- Choose an organization or user scope
- Set access level (public or private)
- Confirm package metadata

<Tip>
  Most packages do not need a scope, but use a scoped name if you are distributing official Codemod packages for a framework or library, or if you are an enterprise team distributing Codemod packages across your organization. Scoped codemods support features like organization-private visibility.
</Tip>

**Unpublishing packages:**

```bash
# Unpublish a specific version
npx codemod unpublish <package-name> --version 1.0.0

# Unpublish all versions (requires --force)
npx codemod unpublish <package-name> --force
```

<Warning>
  Unpublishing is a destructive action. Consider deprecating packages instead of unpublishing if others may depend on them. You must use `--version` to unpublish a specific version, or `--force` to unpublish all versions.
</Warning>

Learn more about the [`publish`](/cli/cli-reference#codemod-publish) and [`unpublish`](/cli/cli-reference#codemod-unpublish) commands.

### Configuring Access and Visibility

In your `codemod.yaml`, configure registry settings:

```yaml codemod.yaml
registry:
  access: "public"      # or "private"
  visibility: "public"  # or "private", "org", "user"
```

**Access levels:**
- `public` – Anyone can run the codemod
- `private` – Only the owner can run the codemod

<Info>
  Pro codemods are reserved for Codemod and their partners. To learn more, [contact the Codemod team](https://codemod.com/contact).
</Info>

**Visibility levels:**
- `public` – Everyone can see the package in search and listings
- `private` – Only the owner can see the package
- `org` – Members of the package's organization scope can see it
- `user` – Visible only to the publishing user

<Tip>
  Access and visibility work together. For example, `visibility: public` with `access: private` shows the package publicly, but only the owner can run it.
</Tip>

Learn more about [configuring packages](/cli/packages/building-workflows#package-metadata-codemod-yaml).

## Publishing from CI/CD

The easiest way to set up CI/CD publishing is to use the [migrations template repository](https://github.com/codemod/migrations-template).

<Card title="Migrations Template" icon="github" href="https://github.com/codemod/migrations-template">
  The migrations template repository includes a preconfigured GitHub Action workflow for automatic publishing.
</Card>

This GitHub template includes:

- Preconfigured GitHub Action workflow for automatic publishing
- Setup instructions for GitHub App installation and API key configuration
- Repository structure optimized for codemod packages

After setup, codemods are automatically published to the registry when PRs are merged. See the template repository for complete setup instructions.

## Using Packages in Workflows

You can reference registry packages in your workflow definitions:

```yaml workflow.yaml
steps:
  - name: Run registry codemod
    codemod:
      source: "@nodejs/create-require-from-path@1.1.0"
```

Learn more about [using Codemod packages in workflows](/cli/packages/building-workflows#codemod-registry-step).

## Best Practices

### Package Naming

- Use descriptive names that indicate the codemod's purpose
- Follow the naming convention: `/^[a-z0-9-_/]+$/`
- Include framework/library names when relevant

**When to use scoped package names:**

Use scoped package names (e.g., `@your-org/package-name`) when:
- **Framework or library maintainers** publishing official codemods for your project
- **Organizations or teams** publishing multiple related codemods that should be grouped together
- You want to **ensure only your organization** can publish codemods with that scope
- You need **better discoverability** for codemods from a specific organization or framework

For individual developers or one-off codemods, unscoped package names are usually the best choice.

### Versioning

- Follow [semantic versioning](https://semver.org/) (MAJOR.MINOR.PATCH)
- Increment major version for breaking changes
- Increment minor version for new features
- Increment patch version for bug fixes

### Documentation

- Write clear descriptions in `codemod.yaml`
- Add relevant keywords for discoverability
- Include examples in your README
- Document any workflow parameters

### Testing

- Test your codemod thoroughly before publishing
- Use [jssg testing](/jssg/testing) for automated test cases
- Validate your workflow with `npx codemod workflow validate`
- Test with real codebases before publishing

## Next steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/cli/cli-reference">
    Complete command reference for registry operations.
  </Card>
  
  <Card title="Building Workflows" icon="diagram-project" href="/cli/packages/building-workflows">
    Learn how to create and configure Codemod packages.
  </Card>
</CardGroup>

<Card title="Codemod Registry" icon="globe" href="https://go.codemod.com/registry">
Browse and discover packages in the web interface.
</Card>
